NAME¶

pmem2_source_device_id() - returns the unique identifier of a device

SYNOPSIS¶

#include <libpmem2.h>
struct pmem2_source;
int pmem2_source_device_id(const struct pmem2_source *source, char *id, size_t *len);

DESCRIPTION¶

The pmem2_source_device_id() function retrieves a unique identifier of all NVDIMMs backing the data source. This function has two operating modes:

•

if *id is NULL the function calculates a buffer length required for storing the identifier of the *source device and puts this length in *len The more hardware devices back the data source, the longer the length is.

•

if *id is not NULL it must point to a buffer of length *len provided by the previous call to this function. On success, pmem2_source_device_id() will store a unique identifier of all hardware devices backing the data source.

For details on how to use the unique identifier for detecting the unsafe shutdown please refer to libpmem2_unsafe_shutdown(7) manual page.

RETURN VALUE¶

The pmem2_source_device_id() function returns 0 on success. If the function fails, the *id and *len variables contents are left unmodified and a negative error code is returned.

ERRORS¶

The pmem2_source_device_id() can fail with the following errors:

On all systems:

•

PMEM2_E_BUFFER_TOO_SMALL - the provided buffer of length *len is too small to store the full identifier of the backing devices.

•

PMEM2_E_NOSUPP - the underlying platform does not expose hardware identification.

On Windows:

•

-errno equivalent of return code set by failing GetFinalPathNameByHandleW(), while trying to resolve the volume path from the file handle.

•

-errno set by failing malloc(3), while trying to allocate a buffer for storing volume path.

•

-errno equivalent of return code set by failing CreateFileW(), while trying to obtain a handle to the volume.

•

-errno equivalent of return code set by failing DeviceIoControl(), while trying to obtain volume USC value.

On Linux:

•

-errno set by failing fstat(2), while trying to validate the file descriptor.

•

-errno set by failing ndctl_new(), while trying to initiate a new NDCTL library context.

SEE ALSO¶

fstat(2), errno(3), malloc(3), libpmem2_unsafe_shutdown(7), and <https://pmem.io>